home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / mc302emb.zip / ASMCF.DOC < prev    next >
Text File  |  1994-03-18  |  42KB  |  901 lines
  1.     
  2.     
  3.     
  4.     
  5.     
  6.     
  7.     
  8.     
  9.     
  10.     
  11.     
  12.     
  13.     
  14.     
  15.     
  16.     
  17.     
  18.     
  19.     
  20.     
  21.                                       XASM
  22.     
  23.                              C-FLEA Cross Assembler
  24.     
  25.                                   Users Guide
  26.     
  27.     
  28.     
  29.     
  30.     
  31.                                   Release 2.2
  32.     
  33.                                Revised 03-Jan-94
  34.     
  35.     
  36.     
  37.     
  38.     
  39.                        Copyright 1983-1994 Dave Dunfield
  40.                               All rights reserved
  41.     XASM Cross Assemblers                                            Page: 1
  42.  
  43.  
  44.     1. INTRODUCTION
  45.     
  46.           This version of XASM included  with  a  MICRO-C  development  kit,
  47.        includes a single cross assembler, and two utility programs:
  48.     
  49.             asmCF       - C-FLEA Assembler
  50.             hexfmt      - HEX file manipulator
  51.             macro       - Macro pre-processor
  52.     
  53.           The XASM "package" (software and  documentation)  is  copyrighted,
  54.        and may not be re-distributed without my written permission.  If  you
  55.        find XASM useful, please help me continue to support and  enhance  it
  56.        by ordering the complete package using the order form in the enclosed
  57.        CATALOG file.
  58.     
  59.           XASM is provided on an "as is" basis,  with  no  warranty  of  any
  60.        kind. In no event shall the author be liable for any damages  arising
  61.        from its use or distribution.
  62.     
  63.           Throughout this document, angle braces ('<>') are used to indicate
  64.        operands for which a value must  be  supplied  by  the  user.  Square
  65.        braces ('[]') are used to identify operands which are optional.
  66.     XASM Cross Assemblers                                            Page: 2
  67.  
  68.  
  69.     2. ASSEMBLERS
  70.     
  71.           All of the cross assemblers read a source file (.ASM), and produce
  72.        a code  file  (.HEX)  containing  either  MOTOROLA  or  INTEL  format
  73.        ASCII-HEX download records. A optional listing file (.LST)  may  also
  74.        be produced.
  75.     
  76.        2.1 Using the assemblers
  77.     
  78.              Any assembler is invoked by entering its name  at  the  command
  79.           prompt, in the following format:
  80.     
  81.                            ASMxx <filename> [options]
  82.     
  83.              The <filename> operand is the name of the file to be assembled,
  84.           it is assumed to have the extension ".ASM" if none is supplied.
  85.     
  86.              Unless otherwise specified, the code produced by the  assembler
  87.           is written to a file  with  the  name  '<filename>.HEX',  and  the
  88.           listing is written to a file with the name '<filename>.LST'.
  89.     
  90.           2.1.1 Command line options
  91.     
  92.                 The following options may be specified on the command  line,
  93.              following the <filename> operand:
  94.     
  95.              -C - [C]ase sensitive
  96.     
  97.                      Causes the assembler  to  make  a  distinction  between
  98.                   upper and lower case characters in symbol  names,  thereby
  99.                   allowing you to have multiple symbol  names  which  differ
  100.                   only in case. If this options is not used,  the  assembler
  101.                   will ignore such case differences,  and  assume  that  the
  102.                   symbols are the same. NOTE: When using this  options,  you
  103.                   must enter any register names in UPPER case.
  104.     
  105.              C=<filename> - Specify [C]ode file
  106.     
  107.                      This option allows you to specify the file to which the
  108.                   output code is written. If no  extension  is  supplied  as
  109.                   part of <filename>, it defaults to ".HEX".
  110.     
  111.              -F - Generate [F]ull listing
  112.     
  113.                      Causes the assembler to output a full source listing to
  114.                   the '.LST' file. By default, only lines containing  errors
  115.                   are written to the listing file.
  116.     
  117.              -I - Generate [I]ntel format HEX file
  118.     
  119.                      Causes the assembler to output the code to  the  '.HEX'
  120.                   file in INTEL hex format. By default the code  is  written
  121.                   to the file in MOTOROLA hex format.
  122.     XASM Cross Assemblers                                            Page: 3
  123.  
  124.  
  125.              L=<filename> - Specify [L]isting file
  126.     
  127.                      This option allows you to specify the file to which the
  128.                   listing is written. If no extension is supplied as part of
  129.                   <filename>, it defaults to ".LST".
  130.     
  131.              O=<value> - [O]ptimization (ASM00,01,02,05,08,09,11,16 and 96)
  132.     
  133.                      This option allows you to set a limit  to  the  maximum
  134.                   number of optimization passes  which  the  assembler  will
  135.                   perform while attempting to minimize code size and resolve
  136.                   forward  referenced  symbols.  If  a  symbol  can  not  be
  137.                   resolved within  this  many  passes,  the  assembler  will
  138.                   terminate with an error message.
  139.     
  140.                      You may specify between 0 and 127  optimization  passes
  141.                   to be run, with  0  being  a  special  case  in  which  no
  142.                   optimization  is  performed.  Without  optimization,   all
  143.                   non-specified memory references  and  offsets  default  to
  144.                   their largest form, and forward references in EQU, ORG, or
  145.                   RMB statements will not work. The code generated will  not
  146.                   be optimal, but assembly time is reduced. This feature  is
  147.                   most useful when initialy testing and debugging a program.
  148.     
  149.                      The default number of optimization passes allowed is 3.
  150.     
  151.              P=<length> - Set page length
  152.     
  153.                      This options specifies the number of lines  which  will
  154.                   be printed on each page. The default number of  lines  per
  155.                   page is 60.
  156.     
  157.              -Q - [Q]uiet mode
  158.     
  159.                      Causes  the  assembler  to  be  quiet,  inhibiting  the
  160.                   display of the progress messages.
  161.     
  162.              -S - Generate [S]ymbol table
  163.     
  164.                      Causes the assembler to sort  and  display  the  symbol
  165.                   table at the end of the  listing  file.  By  default,  the
  166.                   symbol table is not displayed.
  167.     
  168.              -T - Output to [T]erminal
  169.     
  170.                      Causes the assembler  to  output  the  listing  to  the
  171.                   terminal, (via stdout) instead of the usual '.LST' file.
  172.     
  173.         W=<width> - Set page width
  174.     
  175.                 This options control the number of  columns  which  will  be
  176.              used for the printing of  page  titles  and  the  symbol  table
  177.              listing. Default page width is 80 columns.
  178.     XASM Cross Assemblers                                            Page: 4
  179.  
  180.  
  181.        2.2 Redirecting the listing file
  182.     
  183.              When the listing file is directed to the terminal with the '-t'
  184.           option on the command line, it is displayed through  the  standard
  185.           output file, allowing it to be redirected to a  printer  etc.  via
  186.           the shell '>' redirection  operator  (EG:  ASMxx  filename  -f  -t
  187.           >LPT1:). The progress messages ('First pass...'  etc)  are  output
  188.           through stderr, and will therefore  not  be  redirected  with  the
  189.           listing.
  190.     
  191.        2.3 Source file format
  192.     
  193.              The assembly source input lines are in the following format:
  194.     
  195.                 '<label>  <instruction>  <operands>  <comment>'
  196.     
  197.              Labels must begin in column one, and must be separated from the
  198.           instruction field by at least one blank or tab character.
  199.     
  200.              If the an instruction or directive requires operands, then  the
  201.           operand field is required, and is separated from  the  instruction
  202.           by at least one blank or tab.
  203.     
  204.